7 `FRAMverse` and related tools

In addition to using many R tools and packages, the FRAM team has developed a series of R packages and repositories to streamline common tasks. Many of these can be found here: [https://github.com/FRAMverse]

7.1 framrsquared

This package (https://github.com/FRAMverse/framrsquared) provides R functions to interface with FRAM databases, including extracting tables, filtering data, plotting, and even (carefully) modifying the database. Ty Garber is the primary developer of this package.

This package can be installed with devtools or the pak package:

devtools::install_github("FRAMverse/framrsquared")

# Alternatively 
pak::pkg_install("FRAMverse/framrsquared")

The package home page has a good introduction to the package. The following is a brief summary.

7.1.1 Key functions:

Function	Use
`connect_fram_db()`	create connection to database
`disconnect_fram_db()`	disconnect from database
`fetch_table()`	extracts a given table from the database and returns it as an augmented tibble.

7.1.2 Auditing functions:

Function	Use
`compare_fishery_inputs()`	Compares the fishery inputs between two runs
`compare_recruits()`	compares the recruits between two runs
`compare_non_retention_inputs()`	Compares non-retention inputs between two runs
`compare_stock_fishery_rate_scalers()`	Compares stock fishery rate scalers
`compare_runs()`	Generates a report to the console of each of the above
`bkfram_checks()`	Runs a series of checks when carrying out backwards fram

7.1.3 Functions to recreate FRAM reports:

Function	Screen recreated
`msf_mortalities()`	MSF number of mortalities
`msf_encounters ()`	MSF number of encounters
`msf_landed_catch()`	MSF number of landed catch
`population_statistics()`	Populations statistics
`stock_mortality()`	Fishery Mortality

7.1.4 Filter functions:

Function	Filters to…
`filter_sport()`	Sport fisheries
`filter_net()`	Net fisheries
`filter_puget_sound()`	Puget Sound fisheries
`filter_coast()`	Coastal fisheries
`filter_marine()`	Marine fisheries
`filter_wa()`	Washington state fisheries
`filter_bc()`	Canadian fisheries
`filter_ak()`	Alaska fisheries
`filter_or()`	Oregon fisheries
`filter_ca()`	California fisheries

7.1.5 Plotting functions:

Function	Plots…
`plot_stock_mortality()`	Bar chart of top mortalities per fishery
`plot_stock_mortality_time_step()`	… separated by timestep
`compare_inputs_chart()`	Visualize changes in inputs between two runs (takes output of `compare_inputs()`

7.2 TAMMsupport

This package (https://github.com/cbedwards-dfw/TAMMsupport) provides R tools for interacting with TAMM files, including summarizing TAMMs, comparing TAMMs, and extracting key tables. Collin Edwards is the primary developer of this package.

This package can be installed with devtools or the pkg package.

devtools::install_github("cbedwards-dfw/TAMMsupport")

# Alternatively 
pak::pkg_install("cbedwards-dfw/TAMMsupport")

7.2.1 Key functions:

Function	Use
`tamm_diff()`	compares two tamm files and outputs an excel file with diff-like results
`tamm_report()`	summarizes key aspects of a single TAMM file in an html report, including tables and figures
`tamm_compare()`	Generates comparison of two or more TAMM files, using similar elements to the `tamm_report()`

7.2.2 extracting and using data

Function	Use
`read_limiting_stock()`	Reads the limiting stock complete sheet of the TAMM file and handles some simple filtering and formatting
`clean_limiting_stock()`	Like `read_limiting_stock()`, but filters to unmarked natural, removes AEQ entries, and pivots to longform. Useful for plotting
`filter_tamm_wa_chin()`	Filters data fram to washington fisheries based on a `fishery_id` column, using Chinook id numbers)
`filter_tamm_wa_coho()`	As `filter_tamm_wa_chin()`, but based on Coho id numbers

7.2.3 Lookup tables

To simplify translating between ID numbers and names, the TAMMsupport package includes dataframes with columns for stock or fishery id and corresponding names, as well as timestep designations.

dataframe name	Useful for working with…
`stock_chinook_fram`	Chinook stock names and ids
`stock_coho_fram`	Coho stock names and ids
`fishery_chinook_fram`	Chinook fishery names and ids
`fishery_coho_fram`	Coho fishery names and ids
`timestep_chinook_fram`	Chinook timesteps
`timestep_coho_fram`	Coho timesteps

7.3 xldiff

In developing the TAMMsupport package, we discovered there was no reliable R framework for comparing two excel sheets with identical structures but potentially different entries in individual cells. Collin Edwards developed the xldiff package https://github.com/cbedwards-dfw/xldiff to remedy this. The package readme page has thorough documentation of the applications. This package is designed for quick and easy comparisons of individual sheets with excel_diff or as a framework for the development of other tools or packages (e.g., TAMMsupport).

7.4 Snippets

The snippets repository (https://github.com/FRAMverse/snippets) is a storage place for miscellaneous code chunks that might be worth re-using. These include some command-line examples, VB macros, a range of R functions and example code, Quarto and Rmarkdown headers, and the template excel file for summarizing mortality from FRAM databases. The github home page includes an index for all functions and files (possibly excluding recent additions).